home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The CICA Windows Explosion!
/
The CICA Windows Explosion! - Disc 2.iso
/
programr
/
il2hdk31.zip
/
IL2HDK.DOC
< prev
next >
Wrap
Text File
|
1994-04-07
|
24KB
|
549 lines
*******************************************************************************
* il2hdk *
* Interrupt List to help development kit conversion program. *
* Version 3.1, Last Update Apr. 07, 1994. *
*******************************************************************************
What's New
----------
1. Added the interrup.pri to the "additional files" category.
2. Created a OS/2 version of il2hdk.
Overview
--------
il2hdk is a conversion program from Ralf Brown's interrupt list to the help
development kit (hlpdk) .HDF source format.
This program will convert the original interrupt list to a hypertext database
that can be converted using the helpC compiler included with the help
development kit to any one of the target formats supported by this compiler.
This generated database is not intended to replace the interrupt list, it is
just a compilation of the hypertext version. The nice thing about this
hypertext database is that it includes nice hot-links, and easy to use database
structure with categories, indexes and directories, there are glossary
"hints" in the text, and easy to use keyword search is supported.
With the introduction of this tool, and the HPC2HDK conversion program by
Yaniv Golan, 2 of the most interesting reference tools available to PC
programmers are introduced in a hypertext format, in a format you might find
useful.
You might find NG2HDK that converts from the Norton Guides to HLPDK format
another alternative to keep your accumalated wizdom up to date, and POPHDK
that converts from POPHELP to HLPDK as well. (Yaniv Golan's work - again).
Requirments
-----------
In order to use this program you will need the following things :
1. Ralf Brown's interrupt list - available on your favourite sites on the
internet as INTERxxn, where xx stands for the latest version of the
interrupt list (40 is the version number of the list that is available
on the net when this document is written), and n stands for a part number
(A, B or C as of today..).
2. This package (obviously).
3. A PC that can run DPMI applications for the conversion program, with as much
memory as possible. (I have tested this program in an OS/2 VDM restricted
to 2MB of DPMI memory, so it can be assumed that any PC with more than 3MB
of memory will be able to run this program. Please notice, however, that
future versions of the interrupt list might be much bigger than the current
version, so more memory might be needed).
4. The help development kit, a shareware product written by myself, that can
produce help databases or help databases sources to different environments
from the same source. The help development kit is available on the internet
in the simtel hypertext and garbo programming directories, on the WINSDK
forum, WINHELP section of COMPUSERVE and the JCS Marketing shareware CD-ROM.
You can probably find it on other CD-ROMS that include the internet archives,
as well as other sources. The current version is HLPDK 11.0, available as
HDK110A.ZIP, HDK100B.ZIP and HDK100L.ZIP in an archive site/bbs/forum library
near you.
5. [OPTIONAL] - A help compiler for your specific environment - if you do not
generate the code to one of the native help engines included with the
help development kit, the code will have to be compiled with the specific
help compiler.
6. Time, and Disk Space. The interrupt list is BIG, the il2hdk program tries to
convert this list to a smart database with hot-links, and easy navigational
structures. This process takes time, and - Disk Space. (As can be seen in
the 3rd entry of this section above - memory is needed as well).
Operation
---------
0. Well - you know - just do it, oh well, I will be more specific.
1. Move the contents of this package to the directory of the interrupt list
files. (Not mandatory - only recommended).
2. Check the INTLST.LST file provided with this package to see if all the files
of the interrupt list are specified in it, (or if you use the combine.bat
file that came with the interrupt list), and modify it if neccesary.
3. execute the convertor by typing IL2HDK on the command line. (I do not
promise, but you can say that you heard of a GUI icon ridden version,
working as a distributed object with 216 bit technology sometime in the
future).
4. Use to helpC compiler from the help development kit package to compile for
you target. (e.g. To compile for Windows 3.1 - HELPC /W31 /R- INTRPTS).
5. [Optional] - Use your help compiler for the final pass (e.g. - To compile
to Windows 3.1 use the Microsoft HCP program - HCP INTRPTS).
> Please issue IL2HDK /? for a list of the switches available to the
conversion program.
> You may want to add glossary items to the glossary file, or additional
glossary files, please consult the Tech-Talk section below.
File List
---------
This package contains the following files :
IL2HDK .EXE - The convertor program exexcutable.
IL2HDKO .EXE - The convertor program exexcutable - OS/2 native.
DPMI16BI.OVL - Borland's DPMI Server - Needed ONLY with the dos version.
RTM .EXE - Borland's Dos Extender Run Time Module - req. for dos ver. only.
IL2HDK .DOC - This File.
CTGCNV .LST - Category Conversion List Hints file.
INTLST .LST - Default interrupt list file list.
GLSLST .LST - Glossary files list.
PROGRAMS.TXT - HyperAct Inc., other free/shareware products.
Advertisment
------------
Buy 2, Get 3 FREE!. (ACT Now!, A limited time offer).
Known Bugs
----------
0. WHAT???, BUGS???, HERE???, IN MY PROGRAM???. Every thing works as
advertised. (See above).
1. The database is so BIG that some targets supported by the helpC compiler
failed to operate.
A. HC31 will not compile the intrpts.hpj and intrpts.rtf sources created by
helpC. You must use HCP - the protected mode windows help compiler.
B. Borland's Help Linker 6.10 causes exception 12 when it tries to compile
the helpC output using HL -e100 -x -p -i INTRPTS.HL . Maybe Version 6.0
will work. If anyone knows of a way around this, please tell me. (I was
told by Borland Rep. that the problem was sent to QA hopefully for a fix ..).
C. The Native Memory format can not support this database, there are too many
links. The Naive Paradox based format works. (But it is slow in the current
implementation). Version 11.5 of HLPDK which is currently not released,
implements a new huge memory tables technology, and can support the
interrupt list under dos, it is also fast. Stay tuned for the next version
of HLPDK - it might be what you are waiting for !.
D. OS/2 IPF fails, because a topic can have a maximum of 16000 words, and
because some of the directories (such as the interrupt 2f directory) can be
very large, IPFC will fail. IBM's ANN FORD told me on CIS that a future
version of IPF will be a clean 32 bit version, and will support more words
per topic.
E. HCP - Apparantly, if HCP does not have enough memory, it will fail to
create the correct contents screen. The database will be created, but,
the first topic that will be presented is the first topic in the RTF
file. Compiling with HCP in a 8MB DOS VDM under OS/2 works for me, in
a 2MB window, HCP did not create the correct contents topic.
E. I have not tried any other formats, so if you do, please tell me, I assume
that HTML will work ...
2. The helpC compiler failed with a run-time error 203.
A. Some targets can not be compiled in the shareware version of the help
development kit. DV/X, OS/2, POPHELP, Text and Native/Mem targets need
a symbol table that is built by helpC in memory, the shareware version
works in real mode and is restricted to 640K (or a bit more ..), which
is not enough to create the symbol table for such a huge database. Please
use the registered version helpCX protected mode compiler for these
targets. If you use version 11.5 or later, you can also use the new
native OS/2 compiler - HELPCO, that will work.
3. The helpC compiler can not create the Cross Regerence Report.
A. Please use the helpCX protected mode compiler (included with the registered
version of the help development kit). The cross reference report builds
the reference tables in memory, the non-registered version is restricted
to 640K which is not enough for such a huge database.
6. Please inform me of any problems you encountered using this program.
Tech-Talk
---------
This program works like a 2 pass compiler that builds a symbol table on the
first pass, and process the data and hot-links on the 2nd pass. Additional
phases of the convertor create interrupt and category directories that help
the user navigate the database in a heirarchy model.
The convertor will create a unique topic name from each interrupt entry in
the interrupt list, and assign it a title.
The SeeAlso: entries of the list are processed by the convertor, and hot-links
are added. Since the seeAlso: entries do not include direct references to the
topics they should point, a best guess mechanism assisted by a hint list
(included with this package as CTGCNV.LST) tries to associate the entries
with the correct topic. Entries that can not be identified from this data
are being linked to the specific interrupt directory - so even if you will
not be taken to the direct place in the database, you will get close enough.
Index: entries are processed as well, and a link to a menu of all the topics
that has this index is created.
Keywords are defined for every topic, when the database will be compiled, The
user will be able to search on these keywords.
The glossary file glossary.lst is processed by the il2hdk program to create
glossary hints (popups in the hlpdk terminology). If you want to add popus
(glossary items), add a file in the same format as the glossary.lst to
the glslst.lst list file. Notice that if you want to create multiple
instances of the same glossary item, (e.g. VM = Virtual Machine) put
2 entries in your glossary file, and write the text see First Name in the
Second name glossary item. (Look at the glossary.lst file for example).
The reason I decided to create a DPMI program is that in order to achieve
the best guess mechanism I needed to hold a lot of information in a way
I could manage fast, both sequentally and randomly. The obvious idea was to
use either a database indexed table (I would have used the Paradox Engine), or
a virtual memory table. The first approach is too slow, and would require
a lot of disk space, while the 2nd one is fast (as fast as a database as big
as this allows), and more economical in disk space. I figure that if you
are a programmer that needs this kind of information database, you have
a machine capable of running this program. If you MUST run this program
on your 640K PC-XT, contact me, and I will provide you with a version
that uses the Paradox Engine. (+ make sure you can leave your XT on for
the next couple of month).
Distribution
------------
This program is free. I encourage you to try the help development kit by
compiling the output of this program. Please notice however, that the
help development kit is not free, it is a shareware product that you
will have to register (for a very reasonable price) if you find it
valuable. (Registered users of the kit are encouraged to use this program
as well, for no additional cost, of course). Please support the shareware
concept.
The distribution of the interrupt list should be as described by Ralf Brown.
Suggestions
-----------
Please feel free to send me any suggestions, enhancment requests, etc.. for
this program, or the help development kit.
Suggestions for the interrupt list should be sent to Ralf Brown in the address
published in the interrupt list.
Future Plans
------------
A lot - just wait for the next release!
History
-------
- The Jurassic era : A long long time ago.
- July 1993 : The first release of this convertor.
- July 1993 : V1.1 - Keyword support, Enhanced accuracy, winHelp tabs.
1. Use hlpdk 7.0 to compile/display the output of the il2hdk program, there
is a problem with Microsoft's HCP that does not always recognize RTF Tabs
(\tab) if they are not in a group of their own. V7.0 of helpC goes around this
problem by using a RTF group for every TAB, so some of the text will not
be flushed left and invisible. The Native Paradox format help engine is able
to display topics of up to 16K lines, Vs. 500 only, so some of the intrpts
database topics that could not be seen before can be used with this release.
2. Increased the accuracy of the list by the ability to parse hex parameters
that do not appear in the list with a 'h' suffix.
3. Added keywords support. il2hdk will create keyword references from this
version.
- Aug. 1993 : V2.0 - Extended Topics, intlist V3.6 support, Index:,
category reference in topics, glossary, Needs
hlpdk 8.0.
1. Recognize another category - Expansion Bus Bios.
2. Added support for interrupt list V3.6 !xxx category entries.
3. Added support for index: entries in the interrupt list source.
4. Added a link to relevant Category Directory in every topic.
5. Added Glossary file support, as hints (popups) in the database, because
of that this version should be compiled with hlpdk V8.0.
- Sep. 1993 : V2.1 - Text Attributes, Enhanced Keywords search, Needs
hlpdk 9.0.
1. Added keyword search for specific interrupts. If you want to look for
interrupt 21, ax = abcd, you would specify int_21,ax=abcd from the keyword
search menu. This feature was suggested by Stan Brown.
2. Added text attributes to make the database more readable by providing
in-topic section headings in bold.
3. This version needs hlpdk V9.0 to compile the intrpts.hdf output.
- Sep. 1993 : V2.2 - Faster, multi-glossaries per line.
1. il2hdk will give Ralf Brown's special ! topics a more readable title,
and will not take the title from the first topic line.
2. Multiple glossary references can be created on a line.
3. Glossary references will only match complete words. You will not see
a reference to handle as part of the word handler.
4. A glossary item will be created only once per topic, for the first
occurance. You will not have to see (and pay in help file size) for
multiple glossary references of the same link in the same topic.
5. il2hdk pass2 is much faster now. The algorithm is to scan for popups
horizontally vs. vertically as it was done before, so less database access
is needed. (Even when it is in memory it has the price).
6. This version of il2hdk supports "Clash Protection" - Topics that clash
to the same identifier are mapped to unique names, and references are created
between all the topics that clash like that.
- Oct. 1993 : V2.3 - Fixed Bug - support Version 37 of the list.
1. This version was checked on version 37 of the interrupt list, it
fixes a bug, in the il2hdk program, that could (on very rare occasions)
cause a loop while processing the new PCMCIA entries.
- Oct. 1993 : V3.0 - Browse Sequences support, external file
incorporation
1. Added Browse Sequences generation for interrupts and Ralf Brown topics.
2. Incorporate the files MEMORY.LST, PORTS.LST, CMOS.LST AND 86BUGS.LST that
are shiped with the interrupt list to the hypertext database.
3. This version needs HLPDK Sound & Vision Edition (V10.0) to compile.
- Dec. 1993 : V3.1 - OS/2 Version.
HLPDK
-----
The help development kit is a shareware product that allows you to create
your help sources once, and port them to multiple platforms. In V11.0
of the kit, which is the version that was used to test the output of this
program, the supported targets are :
Native (Paradox 4.x & Text)
Native (Memory Tables)
Winhelp 3.0
Winhelp 3.1
MS Multimedia Viewer
OS/2 IPF
THELP (and Borland's IDE)
QuickHelp
POPHELP
TVHC
DESQview/X help
World Wide Web (via HTML) clients - Windows, Unix, Mac, VMS and more...
Text Documents with automatic table of contents, Glossary and index entries.
Word Processors that support the RTF format. (W4W, WP4W, AP etc..)
HLPDK Supports keywords, links, popups, structural and navigation aids (groups)
text attributes, cross reference reports, conditional defines, the ability to
insert target code into the hlpdk source, exception handling and much more.
With HLPDK you can write your documentation once (both for on-line hypertext
documents on several platforms and targets, and for a hard-print as ascii or
fine-print document) once, and re-compile to additional targets.
This version is comapible with HLPDK 11.5, currently in Beta, that supports
The new huge memory tables technology.
Warranty
--------
There is no warranty what so ever, The package is supplied as is,
the author of the conversion program (Loewy Ron), is not, and will not be
responsible for any damages, lost profits, or inconveniences caused by the use,
or inability to use this package. The use of the package is at your own risk.
By using (or attempting to use) the package you agree to this.
The following text is by Ralf Brown, from the interrup.1st file :
---------------------------------------------
DISCLAIMER: THIS MATERIAL IS PROVIDED "AS IS". I verify the information
contained in this list to the best of my ability, but I cannot be held
responsible for any problems caused by use or misuse of the information,
especially for those functions not officially documented. If it is marked
"internal" or undocumented, you should check it carefully to make sure it
works the same way in your version of the software (and please let me know
whether or not it works the same way). Information marked with "???" is
known to be incomplete or guesswork.
---------------------------------------------
To refer to the warranty, choose Ralf Brown Categories from the Category
Directory screen, and refer to Ralf's words. (This information is taken
from interrup.1st).
contact
-------
Please contact :
HyperAct Inc.,
P.O.B 5517
Coralville IA 52241,
U.S.A
HyperAct Inc. e-mail address : Compuserve - 76350,333
internet - 76350.333@Compuserve.Com
To contact the author directly :
e-mail address : CompuServe - 100274,162
*******************************************************************************
* Related Products *
*******************************************************************************
The following products/packages provide additional HLPDK functionality :
1. Name : HPCHDK - HelpPC 2 HLPDK convert program.
Version : 1.0
Availability : HPCHDK10.ZIP.
Status : Free.
Author : Yaniv Golan (s2942275@tech02.technion.ac.il)
2. Name : SCANHELP - Turbo Pascal Scanner to help.
Version : 3.13
Availability : SCANH313.ZIP (Contact Author)
Status : Shareware.
Author : Duncan J. Murdoch (dmurdoch@mast.QueensU.CA)
3. Name : NG2HDK - Norton Guides 2 HLPDK convert program.
Version : 1.0
Availability : NG2HDK10.ZIP
Status : Free.
Author : Ron Loewy.
4. Name : NEWSDB - usenet News Clips Hypertext generator.
Version : 1.0
Availability : NEWSDB10.ZIP.
Status : Shareware.
Author : Ron Loewy.
5. Name : POPHDK - POPHELP 2 HLPDK convert program.
Version : 1.0
Availability : POPHDK10.ZIP.
Status : Free.
Author : Yaniv Golan (s2942275@tech02.technion.ac.il)
6. Name : JARG2HDK - Jargon File to HLPDK convert program.
Version : 1.0
Availability : ? (Contact Author)
Status : ?
Author : Slren Pingel Dalsgaard (pingel@daimi.aau.dk)
7. Name : RC2HDK - Windows Resource File Help Template Generator.
Version : 2.0
Availability : RC2HDK20.ZIP.
Status : Shareware.
Author : Ron Loewy.
8. Name : CPFHDK - C++ FAQ 2 HLPDK convert program.
Version : 1.0
Availability : Contact author.
Status : Free ?
Author : Yaniv Golan (s2942275@tech02.technion.ac.il)
9. Name : CVTOPHLP - OPRO Help 2 HLPDK convert program.
Version : ?
Availability : CIS:PCVENB forum, Sect. TurboPower, CVTHLP.LZH
Status : Free to OPro/TPro owners ?
Author : Julian M. Bucknall, TurboPower Software, CIS:100116,1572
10.Name : TPF2HDK - Timo Salmi's Pascal FAQ 2 HLPDK convert program.
Version : 1.0
Availability : TPFHDK10.ZIP
Status : Free.
Author : Ron Loewy.
Currently under development : RTF2HDK, HDKEDIT and more ..
Credits
-------
The interrupt list copyright notice is :
This compilation is (c) Copyright 1989, 1990, 1991, 1992, 1993, 1994 Ralf Brown.
Additional interrupt list credits can be found in the interrup.1st file
that comes with the interrupt list.
Ralf Brown provided me with description of the interrupt list that allowed
me to create the il2hdk conversion program, he also suggested ideas,
found bugs and informed me of the interrupt list changes.
il2hdk is (c) Copyright 1993,94 HyperAct Inc.
hlpdk is (c) Copyright 1992,94 HyperAct Inc.
il2hdk was written using Borland Pascal 7.0, major parts of this program were
created using dbGen - My own case code generator.
The OS/2 version was created using the C'.T'. magazine Borland Pascal OS/2
patch. Thanks folks!.
HELPENG, HELPC were written using Turbo Pascal 6.0, and Borland Pascal 7.0,
Paradox Engine 2.0, and Paradox Engine 3.0, 3.01.
(Trademarks of Borland International).
Windows, Microsoft, MM Viewer, HC and Quick Help are trademarks or copyrights
of Microsoft Corp.
The HELPENG program was written using the WINTEXT UI library,
(c) 1991,94 Loewy Ron.
THELP, HL and TVHC are Trademarks or copyrights Borland International.
POPHELP is a copyright of TurboPower Software.
Parts of the Help Engines were generated using Ron Loewy's WTGEN and dbGen
CASE code generators.
Parts of the Help Compiler were generated using Ron Loewy's dbGen database
code generator.
Yaniv Golan helped me with beta-testing, debugging and suggestions. He is also
the programmer of the HPC2HDK program (available in an archive site near you)
that convert the HelpPC technical database to the Help Development Kit format.
Yaniv is also the programmer of POPHDK - the POPHELP 2 HLPDK convertor.
(The HelpPC database is a wonderfull hypertext work by David Jurgens).
DESQview/X is a trademark of Quarterdeck Office Systems.
OS/2 is a registered trademark of International Bussiness Machines.
NG2HDK is a Copyright (c) 1993,94 HyperAct Inc.
Stan Brown suggested the additional keywords that supports search by interrupt
number.
Other products mentioned are copyrights or trademarks of their respective
holders.